Pix

O que é o Pix?

O Pix é um meio de pagamento, transferência e recebimento de dinheiro de forma  instantânea. Desenvolvido pelo Banco Central, facilita a forma como as pessoas e empresas realizam suas transações entre si e até mesmo com o Governo.

De forma rápida e segura, o Pix permite que você realize os pagamentos e transferências da sua empresa em até 10 segundos, 24 horas por dia, 7 dias por semana, incluindo finais de semana e feriados. Assim, diferentemente da quitação de boletos ou das transferências tradicionais via DOC e TED, que são processadas apenas em dias úteis, com o Pix as transações são realizadas a qualquer momento e em horários determinados por você, de forma ágil e simples.

Logo do Pix

Como adquirir as credenciais Pix

Para aceitar Pix como meio de pagamento via API, será necessário solicitar ao seu Gerente de Conta (Itaú) as suas Credenciais da API, que são chamadas de: Chave Pix e Client ID.

Atenção: Você pode usar a mesma Credencial/Chave Pix para várias lojas dentro da Maxipago. É necessário verificar se o Token Temporário ainda está dentro da validade de 7 dias e caso não esteja será necessário gerar um novo Token Temporário.

Onde registrar suas credenciais Pix

De posse da suas credenciais Pix você deverá acessar o Portal do Lojista da maxiPago:

  • Ambiente de Testes: Para habiltar o serviço de Pix para testes, entre em contato com a Central E-commerce:
    • Capitais e regiões metropolitanas: (11) 4001-4433
    • Demais localidades: 0800 728 4433
    • E-mail: ecommerce@userede.com.br
  • Ambiente de Produção: https://portal.maxipago.net/vpos/VPOS

1. Acesse o Portal com suas credencias (enviadas no e-mail de boas-vindas)

Login Portal

2. Acesse a aba: Admin – no menu superior (apenas disponível para perfil SuperUser)

3. Acesse a aba: Pix

4. Acesse o submenu: Termo de Uso – conclua o aceite virtual – de acordo com as instruções na tela

5. Acesse o submenu: Credencias – inclua as suas credenciais Pix e clique em Salvar Credenciais

Assim que as credenciais forem registradas, você já poderá começar a utilizar Pix =)

Criando transações Pix

Após a integração com a API do gateway maxipago, basta utilizar os ambientes e requests abaixo:

URL´s para requisições

As URL´s são as mesmas já utilizadas nos processos do gateway. Não há necessidade de nenhuma mudança na chamada do endpoint:

Para gerar Pix – modelo Checkout:

  • Ambiente de Testes: https://testapi.maxipago.net/UniversalAPI/postXML
  • Ambiente de Produção: https://api.maxipago.net/UniversalAPI/postXML

Para gerar Pix – modelo Link de Pagamento:

  • Ambiente de Testes: https://testapi.maxipago.net/UniversalAPI/postAPI
  • Ambiente de Produção: https://api.maxipago.net/UniversalAPI/postAPI

Criação de Pix – modelo checkout

O modelo checkout é utilizado por lojistas que possuem ambiente de e-commerce já preparado para receber os dados de seus consumidores.

Exemplo de XML para cobrança Pix

<transaction-request>
    <version>3.1.1.15</version>
    <verification>
        <merchantId>store-id</merchantId>
        <merchantKey>store-key</merchantKey>
    </verification>
    <order>
        <sale>
            <processorID>206</processorID>
            <referenceNum>MXP_PIX_130120211126</referenceNum>
            <customerIdExt>37568256634</customerIdExt>
            <billing>
                <name>maxipixPago</name>
                <address>Avenida Paulista 123</address>
                <address2>1 Andar</address2>
                <district>Paraiso</district>
                <city>Sao Paulo</city>
                <state>SP</state>
                <postalcode>01311000</postalcode>
                <country>BR</country>
                <phone>36925873229</phone>
                <email>testepix@testepix.com</email>
                <documents>
                    <document>
                        <documentType>CPF</documentType>
                        <documentValue>99907514047</documentValue>
                    </document>
                </documents>
            </billing>
            <transactionDetail>
                <payType>
                    <pix>
                        <expirationTime>86400</expirationTime>
                        <paymentInfo>Smart TV LG 65´ 8K IPS NanoCell, Conexão WiFi e Bluetooth</paymentInfo>
                        <extraInfo>
                            <info>
                                <name>TV8k</name>
                                <value>R$10.000,00</value>
                            </info>
                            <info>
                                <name>Garantia Estendida</name>
                                <value>R$5.00</value>
                            </info>
                        </extraInfo>
                    </pix>
                </payType>
            </transactionDetail>
            <payment>
                <chargeTotal>10005.00</chargeTotal>
            </payment>
        </sale>
    </order>
</transaction-request>

Exemplo de retorno da Requisição de criação Pix – Cenário de Sucesso

<?xml version="1.0" encoding="UTF-8"?>
<transaction-response>
	<authCode/>
	<orderID>0A0115FA:017F0AE6BC49:F48F:448638D3</orderID>
	<referenceNum>MXP_PIX_1303232126</referenceNum>
	<transactionID>435962287</transactionID>
	<transactionTimestamp>1645155368</transactionTimestamp>
	<responseCode>0</responseCode>
	<responseMessage/>
	<avsResponseCode/>
	<cvvResponseCode/>
	<processorCode>A</processorCode>
	<processorMessage>APPROVED</processorMessage>
	<processorName>PIXSIMULATOR</processorName>
	<errorMessage/>
	<processorTransactionID>310663</processorTransactionID>
	<processorReferenceNumber>630054</processorReferenceNumber>
	<onlineDebitUrl>https://authentication.maxipago.net/redirection_service/auth?ref=W4TpNURotaJUW9jprYiAK1TPYDi0LvO1XEK5CanaeV%2FHdhcaC70EcPiDSoFP%2FxtBtiB%2F9Z%2FmP477%0AxAXCEhSxRbvj0%2Frb1QxL</onlineDebitUrl>
	<emv>00020101021226950014br.gov.bcb.pix210812345678220412342309123445678242001234567890123456789520400005303986560510.005802BR5932maxiPago Servicos de Internet SA6009S�o Paulo62190515T0I435962287I0T80760014br.gov.bcb.pix2546bx.com.br/pix/0A0115FA017F0AE6BC49F48F448638D363049E9D</emv>
	<imagem_base64>iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAAEEUlEQVR42u2ZMY6jQBBFyyLozFwAiWt0xpXsCxi4AFyps74GEheArANE7Stvsp6VNqE2s2WNRrtPgmr+/1XFiP77k+QLfIEv8AX+BQxSbWHpUzWm5dGtZ6zmtIh4ArOuc2oecd1Luxe5x1bTqsUTmGQdM1dfbmk9u8Z+yjpEZ0Bz8yzNrUifjx44+gNzOfokdZE6ySMcr+AM2EmWSvNRJzWyUOxfR30NQA9TXD+/PwVzEXgz3Ek1iU4RSXBLP2V/ETAxhOPRyUP4mDbuga8ncIbjpktfqj23fOfET+ThCUxR7t06hWoIh8jRKw+uqV0Bzm3Aj3yyjiYPim1u6glMIi++YXkJp6qmBwovngDVvbrjHpoHrhe56aqp/dM41wE0XKej5vR4RpSZ16E7nskT2NWK2iyQCcx2Li2qq9UTwPujyqOrzJIEcqJY7OkJqDY45RUpkxuQZz4eoZ2LJzDFStNxS9XWLXVpz9iOFJ49ga3DJvidYGn6woMjapp79AQmqc6I3pY+65yQ30K9p7gCgStinPUM7URbVI5U9+IJnGEdS/Okvws9C/kJqphdgU2QsbwiZMOgMlNjp3t2BWJ1huXJ2BBRuN1PndG5J0BwzWoH+CzrFg9afG9DkSeAqvG7hFaZUpjockPb3cQTGEmwhCXlWWhe5sr5HfuOwJ7oWWJRTPOKK1cnkCV6Agw8UzwehIBdnWNst4ibPIEhogE6yPKwoa7i99FU4Qnw+9RVsxKV1oWJ/THRyHwBYZam4Y5JbuW4d2QmJvUE6Fm4ZuqYtaxn7YkoWHr1BAaMSaXEb8fQjgI5z/XjYV0HUFeu5vcsN6aKHeTeYR9PYM7VwNXDSnPfbPVoSYOnegI8+i0w/JCT5vrZEmZ5RE9gExpuI6g6VmwKw9ukL/EE5tzcctPn1pRsrsH+yzN7ArbGsiyLdXaxEGhR+NZ5ApO0u667NuwgT45RWzvY7AmMaq5kbOgVoFWr+qPzOgCJSps6WXYh753mW9jTPYEhiLCpSaXKRE0OMHeROZ4As+JdGsp8BdPzjXFFPza168ApjFiNdBXL7MRjepdZuwIMPGdnOyCLJw6qdZFO6uwJsBpIZI1qB/49LYy7Q6d/rlHXAdruE/uHis612W0sf01BV4GTuVpwJZaxfYdlU8JHwlwHqGhWe/0yBIv6vlgX7rMrEBAzTYSbEbR3F2YJqYsn8LanMJ9o+r3etmT+mDwBEv49+djLMYDX++XeXDyBWQleayhYHoxlcE/647XbRYBL84xqBkVi35aRyuai4gzQ0PdMK1nYEXp71/q583oAagsOUWkLCD2l1p9lXgQ4yUGOly22pA3/i3GOj9dNlwH0QH+3KI4HnXeyub39IbmLwPfPE1/gC3yB/wL8AhX75MN7+GBJAAAAAElFTkSuQmCC</imagem_base64>
</transaction-response>

 Tabela de Retorno da Requisição de criação Pix

Exemplo da Requisição criação Pix (modelo checkout) – Cenário de Erro

<?xml version="1.0" encoding="UTF-8"?>
<transaction-response>
	<authCode/>
	<orderID/>
	<referenceNum/>
	<transactionID/>
	<transactionTimestamp>1614962010197</transactionTimestamp>
	<responseCode>1024</responseCode>
	<responseMessage>INVALID REQUEST</responseMessage>
	<avsResponseCode/>
	<cvvResponseCode/>
	<processorCode/>
	<processorMessage/>
	<processorName>PIXSIMULATOR</processorName>
	<errorMessage>Reference Number is a required field.</errorMessage>
</transaction-response>

Tabela de Parâmetros Pix – modelo Checkout

Criação de Pix – modelo Link de Pagamento

O modelo Link de Pagamento é utilizado por lojistas desejam enviar o link de cobrança seja por e-mail, whatsapp ou outra Rede Social. Ele permite que mesmo lojistas sem ambiente de checkout ou site possam enviar suas cobranças.

A requisição de link de pagamento sempre será enviada com o parâmetro <creditCard>, não é possível gerar um Link apenas com Pix como meio de pagamento.

Fique tranquilo, se o primeiro pagamento for o Pix, automaticamente o Link será considerado PAGO e uma nova tentativa de pagamento não será permitida. O contrário também é válido, se o primeiro pagamento for com o cartão de crédito, o Link será considerado PAGO e uma tentativa de pagamento não será permitida.

Exemplo de XML para cobrança Pix no Link de Pagamento

<api-request>
    <verification>
        <merchantId>xxxxxxx</merchantId>
        <merchantKey>xxxxxx</merchantKey>
    </verification>
    <command>add-payment-order</command>
    <request>
        <consumerAuthentication>N</consumerAuthentication>
        <referenceNum>2009171040</referenceNum>
        <fraudCheck>N</fraudCheck>
        <billing>           
            <email>dev@maxipago.com</email>
            <language>pt</language>
            <firstName>Dev</firstName>    
        </billing>
        <transactionDetail>
            <description>pagamento Smart TV</description>           
            <emailSubject>Favor efetuar o pagamento</emailSubject>
            <expirationDate>06/17/2022</expirationDate>
            <acceptPix>Y</acceptPix>
            <payType>
                <creditCard>                   
                    <amount>2.00</amount>
                </creditCard>
            </payType>
        </transactionDetail>      
    </request>
</api-request>

Exemplo de XML para cobrança Pix no Link de Pagamento – Sucesso

<?xml version="1.0" encoding="UTF-8" ?>
<api-response>
    <errorCode>0</errorCode>
    <errorMessage></errorMessage>
    <command>add-payment-order</command>
    <time>1645571886595</time>
    <result>
        <pay_order_id>kk2p5mp7</pay_order_id>
        <message>Inserted Successfully</message>
        <url>https://secure.maxipago.net/maxipay/#!/fp?p=kk2p5mp7</url>
        </result>
</api-response>

Exemplo de XML para cobrança Pix no Link de Pagamento – Erro

<?xml version="1.0" encoding="UTF-8" ?>
<api-response>
    <errorCode>1</errorCode>
    <errorMessage>
        <![CDATA[Unable to authenticate merchant]]>
    </errorMessage>
    <time>1645574178347</time>
</api-response>

Casos de Cancelamento (VOID) de um Pix

Pode acontecer do lojista precisar cancelar uma transação Pix; neste caso, é possível enviar uma solicitação de VOID. Este caso serve apenas para situações em que o lojista deseja cancelar a cobrança Pix. Neste cenário, o Pix não pode ter sido pago.

Exemplo de Requisição de Cancelamento (VOID) Pix

<transaction-request>
	<version>3.1.1.15</version>
	<verification>
		<merchantId>store-id</merchantId>
		<merchantKey>store-key</merchantKey>
	</verification>
	<order>
		<void>
			<transactionID>435962287</transactionID>
		</void>
	</order>
</transaction-request>

Exemplo de Requisição de Cancelamento (VOID) Pix – Cenário de Sucesso

<?xml version="1.0" encoding="UTF-8"?>
<transaction-response>
    <authCode/>
    <orderID/>
    <referenceNum>MXP_PIX_1303232126</referenceNum>
    <transactionID>435962287</transactionID>
    <transactionTimestamp/>
    <responseCode>0</responseCode>
    <responseMessage>VOIDED</responseMessage>
    <avsResponseCode/>
    <cvvResponseCode/>
    <processorCode/>
    <processorMessage/>
    <processorName>PIXSIMULATOR</processorName>
    <errorMessage/>
</transaction-response>

Exemplo de Requisição de Cancelamento (VOID) Pix – Cenário de Erro

<?xml version="1.0" encoding="UTF-8"?>
<transaction-response>
	<authCode/>
	<orderID/>
	<referenceNum>MXP_PIX_1303232126</referenceNum>
	<transactionID>435962287</transactionID>
	<transactionTimestamp/>
	<responseCode>1</responseCode>
	<responseMessage>Error on void transaction ....</responseMessage>
	<avsResponseCode/>
	<cvvResponseCode/>
	<processorCode/>
	<processorMessage/>
	<processorName>PIXSIMULATOR</processorName>
	<errorMessage/>
</transaction-response>

Tabela de Parâmetros – Cancelamento (VOID)

Casos de Estorno de Pix

Quando houver a necessidade do lojista devolver um valor ao consumidor, ele poderá enviar uma requisição de estorno.

Exemplo de Requisição de Estorno Pix

<transaction-request>
    <version>3.1.1.15</version>
    <verification>
        <merchantId>store-id</merchantId>
        <merchantKey>store-key</merchantKey>
    </verification>
    <order>
        <pixReturn>
            <orderID>0A0115B1:017F0B15166E:C6AA:06ACF34A</orderID>
            <referenceNum>MXP_PIX_130120211126</referenceNum>
            <payment>
                <chargeTotal>15.00</chargeTotal>
            </payment>
        </pixReturn>
    </order>
</transaction-request>

Exemplo de Requisição de Estorno Pix – Cenário de Sucesso

<?xml version="1.0" encoding="UTF-8"?>
<transaction-response>
    <authCode/>
    <orderID>0A0115B1:017F0B15166E:C6AA:06ACF34A</orderID>
    <referenceNum>123</referenceNum>
    <transactionID>13428822</transactionID>
    <transactionTimestamp>13428822</transactionTimestamp>
    <responseCode>0</responseCode>
    <responseMessage>CAPTURED</responseMessage>
    <avsResponseCode/>
    <cvvResponseCode/>
    <processorCode>201</processorCode>
    <processorMessage>DEVOLVIDO</processorMessage>
    <processorName>PIXSIMULATOR</processorName>
    <errorMessage/>
    <processorTransactionID>D6070119020211007160459251248577</processorTransactionID>
</transaction-response>

Exemplo de Requisição de Estorno Pix – Cenário de Erro

<?xml version="1.0" encoding="UTF-8"?>
<transaction-response>
    <authCode/>
    <orderID>0A0115B1:017F0B15166E:C6AA:06ACF34A</orderID>
    <referenceNum>MXP_PIX_130120211126</referenceNum>
    <transactionID/>
    <transactionTimestamp>1645158523569</transactionTimestamp>
    <responseCode>1024</responseCode>
    <responseMessage>INVALID REQUEST</responseMessage>
    <avsResponseCode/>
    <cvvResponseCode/>
    <processorCode/>
    <processorMessage/>
    <processorName>PIXITAU</processorName>
    <errorMessage>Only transactions Captured or Settled can be returned</errorMessage>
</transaction-response>

Tabela de Parâmetros – Estorno

E as notificações?

Foram preparados 2 tipos de retorno para as transações Pix

Exemplo Webhook Pix – Transação com Sucesso

xml=
<?xml version="1.0" encoding="UTF-8"?>
<Request>
    <transaction-event>
        <transactionStatus>3</transactionStatus>
        <transactionType>PixSale</transactionType>
        <transactionID>13494912</transactionID>
        <tid>1006993069000AC96D2A</tid>
        <orderID>0A01049C:017D4824A517:6280:5556432E</orderID>
        <transactionState>Captured</transactionState>
        <transactionDate>08-19-2017 00:56:27</transactionDate>
        <merchantId>1501</merchantId>
        <transactionAmount>24.00</transactionAmount>
        <referenceNumber>20200001</referenceNumber>
        <nsu>123</nsu>
    </transaction-event>
</Request>

Exemplo Webhook Pix Expirado

*Importante: um Pix expirado será automaticamente cancelado.

<?xml version="1.0" encoding="UTF-8"?>
<Request>
    <transaction-event>
        <transactionStatus>9</transactionStatus>
        <transactionType>PixSale</transactionType>
        <transactionID>434763143</transactionID>
        <orderID>0A0115E9:017EE035B916:5370:6E246F14</orderID>
        <transactionState>Voided</transactionState>
        <transactionDate>02-09-2022 17:38:44</transactionDate>
        <merchantId>store-id</merchantId>
        <referenceNumber>MXP_PIX_202202091836</referenceNumber>
        <transactionAmount>0.01</transactionAmount>
    </transaction-event>
</Request>

Suporte ao Cliente maxiPago!

E-mail: suporte@maxipago.com
Telefone: (11) 3003-0603 – Capitais e Regiões Metropolitanas
0800 723 0603 – Demais Localidades